.TH ASSEMBLYLINE 3 2022-01-21 GNU

.SH NAME
assemblyline \- C library functions for generating machine code of intel x86_64 assembly language without invoking another compiler, assembler or linker 

.SH DESCRIPTION
This library provides a method to generate machine code from intel x86_64 assembly instructions on-the-fly. Machine code can be written to a buffer passed as argument for \fBasm_create_instance(3)\fR or an interal dynamically allocated buffer within assemblyline. An external buffer must be greater than 20 bytes. An error will the thrown if written length exceeds (buffer length - 20). There is no size limit when using an internal buffer.
.br
\fBNOTE:\fR assemblyline does not check for mismatch operand size/type when using pointers
.br 
      ie. mov qword [rbp], al will be intepreted as mov qword [rbp], rax

.SH SYNOPSIS
.TP
.BR #include " "<assemblyline.h>
.TP
.BI "assemblyline_t asm_create_instance(uint8_t *" buffer ", int " len );
Allocates an instance of assemblyline_t and attaches a pointer to a memory \fIbuffer\fR where machine code will be written to. Buffer length will be specified by \fIlen\fR.
.br
\fBNOTE:\fR \fIbuffer\fR could also be set to NULL for internal memory allocation. In this case \fIlen\fR would be irrelevant and could be set to any number.

.TP
.BI "int asm_destroy_instance(assemblyline_t " instance );
Frees all memory associated with \fIinstance\fR. Returns EXIT_SUCCESS or EXIT_FAILURE.

.TP
.BI "int asm_assemble_str(assemblyline_t " al ", const char *" assembly_str );
Assembles the given string \fIassembly_str\fR containing valid x64 assembly code with instance \fIal\fR. It writes the corresponding machine code to the memory location specified by the buffer associated with \fIal\fR. Returns EXIT_SUCCESS or EXIT_FAILURE.

.TP
.BI "int asm_assemble_file(assemblyline_t " al ", char *" asm_file );
Assembles the given file path \fIasm_file\fR containing valid x64 assembly code with instance \fIal\fR. It writes the corresponding machine code to the memory location specified by the buffer associated with \fIal\fR. Returns EXIT_SUCCESS or EXIT_FAILURE.

.TP
.BI "int asm_assemble_string_counting_chunks(assemblyline_t " al ", char *" str ", int " chunk_size ", int *" dest );
Assembles the given null-terminated string \fIstr\fR with instance \fIal\fR. It counts the number of instructions that break the chunk boundary of size \fIchunk_size\fR and saves it to \fIdest\fR. It does not nop-pad by default, depends on instance \fIal\fR (you can nop-pad and count different chunk breaks). Returns EXIT_SUCCESS or EXIT_FAILURE.

.br
\fBNOTE:\fR you cannot pass const char* as \fIstr\fR, it will segfault, because string will be altered.

.TP
.BI "int asm_assemble_file_counting_chunks(assemblyline_t " al ", char *" asm_file ", int " chunk_size ", int *" dest );
Assembles the given file \fIasm_file\fR with instance \fIal\fR. It counts the number of instructions that break the chunk boundary of size \fIchunk_size\fR and saves it to \fIdest\fR. It does not nop-pad by default, depends on instance \fIal\fR (you can nop-pad and count different chunk breaks).

.TP
.BI "void asm_set_chunk_size(assemblyline_t " al ", size_t " chunk_size );
Sets a given chunk size boundary \fIchunk_size\fR in bytes with instance \fIal\fR. When called before assemble_str() or assemble_file() assemblyline will ensure no instruction opcode will cross the specified \fIchunk_size\fR boundary via nop padding.
.br
\fBNOTE:\fR \fIchunk_size\fR must be greater than 2 in order to be classified as a valid memory chunk boundary size.

.TP
.BI "void asm_set_debug(assemblyline_t " al ", bool " debug );
Set debug flag \fIdebug\fR to true or false with instance \fIal\fR. When is set \fIdebug\fR to true machine code represented in hexidecimal will be printed to stdout.

.TP
.BI "int asm_get_offset(assemblyline_t " al );
Returns the offset associated with \fIal\fR.

.TP
.BI "void asm_set_offset(assemblyline_t " al ", int "offset );
Sets a memory \fIoffset\fR to specify exact location in memory block for writting machine code with instance \fIal\fR\.
.br
\fBNOTE:\fR \fIoffset\fR could be set to 0 for the resulting memory block.

.TP
.BI "void *asm_get_code(assemblyline_t " al );
Returns the buffer associated with \fIal\fR as type void* for easy typecasting to any function pointer format.

.TP
.BI "uint8_t *asm_get_buffer(assemblyline_t " al );
Returns the buffer associated with \fIal\fR (DEPRECATED: use \fBasm_get_code(3)\fR instead).

.TP
.BI "int asm_create_bin_file(assemblyline_t " al ", char *" file_name );
Generates a binary file \fIfile_name\fR from assembled machine code up to the memory offset of the current instance \fIal\fR. Returns EXIT_SUCCESS or EXIT_FAILURE.

.TP
.BI "void asm_mov_imm(assemblyline_t " al ", enum asm_opt "option );
Setting \fIoption\fR to STRICT disables nasm-style mov-immediate register-size handling. where even if immediate size for mov is less than or equal to max signed 32 bit assemblyline will pad the immediate to fit 64bit.
.br
\fBThat is:\fR "mov rax,0x7fffffff" as "mov rax,0x000000007fffffff" 
.br
          -> 48 b8 ff ff ff 7f 00 00 00 00

.br
Setting \fIoption\fR to NASM enables nasm-style mov-immediate register-size handling where if the immediate size for mov is less than or equal to max signed 32 bit assemblyline will emit code to mov to 32-bit register rather than 64-bit.
.br
\fBThat is:\fR "mov rax, 0x7fffffff" as "mov eax, 0x7fffffff" -> b8 ff ff ff 7f

.br
Setting \fIoption\fR to SMART, Assemblyline will check the immediate value for leading 0's and thus allows manual handlings. This is currently set as default.
.br
\fBex:\fR "mov rax, 0x000000007fffffff" ->  48 b8 ff ff ff 7f 00 00 00 00
.br
    "mov rax, 0x7fffffff" -> b8 ff ff ff 7f

.br
.br
Setting \fIoption\fR to any other value results in an no-operation function.

.TP
.BI "void asm_sib_index_base_swap(assemblyline_t " al ", enum asm_opt "option );
Since the stack pointer register is non-scalable in SIB, Nasm will swap the base and index register if the stack pointer register is used as the index.

.br
Setting \fIoption\fR to STRICT disables Nasm SIB handling.
.br
\fBThat is:\fR "lea r15, [rax+rsp]" will be interpreted as "lea r15, [rax+riz]"
.br
         -> 4c 8d 3c 20
.br
\fBNOTE:\fR riz is a pseudo-register evaluated by GCC to constant 0 and therefore cannot be used in assemblyline as a string ie. assembling "lea r15, [rax+riz]" is invalid "lea r15, [rsp+rsp]" will produce an error (invalid instruction)

.br
Setting \fIoption\fR to NASM enables Nasm SIB handling. This is currently set as default.
.br
\fBThat is:\fR "lea r15, [rax+rsp]" will be interpreted as "lea r15, [rsp+rax]"
         -> 4c 8d 3c 04
.br
         "lea r15, [rsp+rsp]" will produce an error because
.br
         base and index cannot be swapped

.br
Setting \fIoption\fR to SMART or any other value results in an no-operation function.

.TP
.BI "void asm_sib_no_base(assemblyline_t " al ", enum asm_opt "option );
In SIB, when no base register is present and the scale is equal to 2; NASM will set the base to the index register and reduce the scale by 1. \fBex:\fR [2*rax] -> [rax+1*rax]

.br
Setting \fIoption\fR to STRICT disables Nasm SIB handling with no base.
.br
\fBThat is:\fR "lea r15, [2*rax]" will be interpreted as is
.br
         -> 4c 8d 3c 45 00 00 00 00

.br
Setting \fIoption\fR to NASM enables Nasm SIB handling with no base. This is currently set as default.
.br
\fBThat is:\fR "lea r15, [2*rax]" will be interpreted as "lea r15, [rax+1*rax]"
.br
         -> 4c 8d 3c 00

.br
Setting \fIoption\fR to SMART or any other value results in an no-operation function.

.TP
.BI "void asm_sib(assemblyline_t " al ", enum asm_opt "option );
Setting \fIoption\fR to STRICT is equivalent to calling both \fBasm_sib_index_base_swap(al,STRICT)\fR and \fBasm_sib_no_base(al,STRICT)\fR.

.br
Setting \fIoption\fR to NASM is equivalent to calling both \fBasm_sib_index_base_swap(al,NASM)\fR and \fBasm_sib_no_base(al,NASM)\fR.

.br
Setting \fIoption\fR to SMART or any other value results in an no-operation function.

.TP
.BI "void asm_set_all(assemblyline_t " al ", enum asm_opt "option );
Setting \fIoption\fR to STRICT is equivalent to calling \fBasm_sib_index_base_swap(al,STRICT)\fR, \fBasm_sib_no_base(al,STRICT)\fR, and \fBasm_mov_imm(al,STRICT)\fR.

.br
Setting \fIoption\fR to NASM is equivalent to calling \fBasm_sib_index_base_swap(al,NASM)\fR, \fBasm_sib_no_base(al,NASM)\fR, and \fBasm_mov_imm(al,NASM)\fR.

.br
Setting \fIoption\fR to SMART is equivalent to calling \fBasm_mov_imm(al,SMART)\fR.

.br
Setting \fIoption\fR to any other value results in an no-operation function.

.SH SEE ALSO
.B asmline(1)